feat(web,server): support custom provider - #146

Summary

This PR introduces a comprehensive backward compatibility and fallback system for tile/terrain providers, integrates Sentinel for authenticated asset access, and updates the data attribution system. The changes ensure existing projects continue working while gracefully handling migration to new provider types.

Statistics: 48 files changed, 5,292 insertions(+), 94 deletions(-)

🎯 Major Features

1. Compatibility System (New)

A complete backward compatibility and fallback system for scene properties.

Frontend (web/src/classic/components/molecules/Visualizer/compatibility/):

• ✅ Backward Compatibility Layer - Automatically migrates legacy provider types to new ones
  • Tile migrations: default → cesium_ion, stamen_toner → open_street_map, etc.
  • Terrain migrations: arcgis → reearth_terrain
• ✅ Fallback System - Gracefully handles missing Cesium Ion tokens
  • Falls back to alternative providers (e.g., cesium_ion → google_satellite)
• ✅ Comprehensive Testing - 48 tests covering all migration and fallback scenarios
• ✅ Full Documentation - 3 detailed markdown docs (README, BACKWARD_COMPATIBILITY, FALLBACKS)

Migration Rules Applied:

2. Database Migrations (Server)

New Migration Scripts:

• 260525000715_update_tile_and_terrain_providers.go - Forward migration for tile/terrain types
• 260525000715_revert_tile_and_terrain_providers.go - Recovery migration (not auto-registered)
• Comprehensive test coverage for both migrations

Migration Safety:

• ✅ Merges two previous migrations into one unified script
• ✅ Includes revert script for rollback scenarios
• ✅ Preserves existing data and custom asset IDs
• ✅ Only migrates specific known types (doesn't touch undefined/unknown types)

3. Sentinel Integration (New)

Secure, authenticated asset access through Bearer token authentication.

Features:

• 🔒 Service Worker-based request interception
• 🔑 Automatic Bearer token injection for protected domains
• ⏱️ Token expiration management
• 📝 Comprehensive API with status checking

Files Added:

• web/src/services/sentinel/ - Service implementation
• public/sentinel-sw.js - Service worker (701 lines)
• Full README with usage examples

Configuration:

REEARTH_WEB_TILE_SERVER_BASE_URL=https://your-tile-server.example.com
REEARTH_WEB_TILE_SERVER_TOKEN=your-bearer-token-here

4. Data Attribution Updates

Improvements:

• ✅ Updated widget layout and alignment system
• ✅ Enhanced content modal for better credit display
• ✅ Improved useCredits hook for data attribution

5. Tile/Terrain Provider Updates

New Presets Added (web/src/classic/components/molecules/Visualizer/Engine/Cesium/core/presets.ts):

• Additional tile provider configurations (+62 lines)
• Enhanced terrain provider support
• Tileset customization options

🔧 Bug Fixes

Imagery Provider Recreation

File: web/src/classic/components/molecules/Visualizer/Engine/Cesium/core/Imagery.tsx

Issue: Imagery providers weren't being recreated when cesiumIonAccessToken changed for tiles using Cesium Ion (like default, default_label, etc.)

Fix: Extended token change detection to include all Cesium Ion-dependent tile types:
// Now recreates provider for these tile types when token changes:

• cesium_ion
• default
• default_label
• default_road
• black_marble

Result: ✅ Test Imagery.test.ts now passes

📊 Test Coverage

Frontend Tests

• ✅ 48 compatibility tests (100% passing)
  • 19 backward compatibility tests
  • 22 fallback tests
  • 7 integration tests
• ✅ 1 Imagery test (fixed and passing)

Backend Tests

• ✅ Forward migration tests (6 test suites)
• ✅ Revert migration tests (6 test suites, including round-trip verification)

Total: 55+ tests added/updated

📝 Documentation Added

1. Compatibility System:
   - web/src/classic/components/molecules/Visualizer/compatibility/README.md (179 lines)
   - BACKWARD_COMPATIBILITY.md (156 lines)
   - FALLBACKS.md (218 lines)
2. Sentinel:
   - web/src/services/sentinel/README.md (133 lines)

Total: 686 lines of documentation

🔄 Data Flow

Input: sceneProperty
↓
[1] Apply plugin overrides (useOverriddenProperty)
↓
[2] Apply backward compatibility (migrate old types)
↓
[3] Apply fallbacks (if no Cesium Ion token)
↓
Output: Transformed sceneProperty

⚙️ Configuration Changes

Docker (web/docker/reearth_config.json.template):

• Added Sentinel configuration options
• Updated tile server settings

Package (web/package.json):

• Added @reearth/sentinel dependency

🎯 Breaking Changes

None - This PR is fully backward compatible:

• ✅ Old projects automatically migrated
• ✅ Missing Cesium Ion tokens handled gracefully
• ✅ Existing data preserved
• ✅ Revert migration available if needed

🚀 Migration Path

1. Automatic Frontend Migration: Old tile/terrain types automatically converted on load
2. Database Migration: Runs automatically on server startup (migration 260525000715)
3. Rollback Available: Use RevertTileAndTerrainProviders() if needed (manual call)

📦 Files Changed

Added (18 files)

• Compatibility system (8 files: implementation + tests + docs)
• Sentinel service (3 files: implementation + docs + service worker)
• Migration scripts (4 files: forward + revert + tests)
• Service worker copies (2 files: public + web/public)
• Config types (1 file)

Modified (30 files)

• Imagery provider logic
• Data attribution widgets
• Widget alignment system
• Globe and tileset configurations
• Auth integration (Auth0, Cognito)
• Config loading
• Docker and build configurations

✅ Checklist

• All tests passing (48 compatibility + 12 migration + 1 imagery)
• Documentation complete and comprehensive
• Backward compatibility verified
• Migration scripts tested
• Revert script available
• No breaking changes
• Code builds successfully